<!DOCTYPE html>

<html>
  <head>
    <meta charset="utf-8">
    
    <title>A Guide to NumPy/SciPy Documentation &mdash; NumPy v1.18 Manual</title>
    
    <link rel="stylesheet" type="text/css" href="../_static/css/spc-bootstrap.css">
    <link rel="stylesheet" type="text/css" href="../_static/css/spc-extend.css">
    <link rel="stylesheet" href="../_static/scipy.css" type="text/css" >
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" >
    <link rel="stylesheet" href="../_static/graphviz.css" type="text/css" >
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '../',
        VERSION:     '1.18.1',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  false
      };
    </script>
    <script type="text/javascript" src="../_static/jquery.js"></script>
    <script type="text/javascript" src="../_static/underscore.js"></script>
    <script type="text/javascript" src="../_static/doctools.js"></script>
    <script type="text/javascript" src="../_static/language_data.js"></script>
    <script type="text/javascript" src="../_static/js/copybutton.js"></script>
    <link rel="author" title="About these documents" href="../about.html" >
    <link rel="index" title="Index" href="../genindex.html" >
    <link rel="search" title="Search" href="../search.html" >
    <link rel="top" title="NumPy v1.18 Manual" href="../index.html" >
    <link rel="up" title="NumPy’s Documentation" href="index.html" >
    <link rel="next" title="Building the NumPy API and reference docs" href="howto_build_docs.html" >
    <link rel="prev" title="NumPy’s Documentation" href="index.html" > 
  </head>
  <body>
<div class="container">
  <div class="top-scipy-org-logo-header" style="background-color: #a2bae8;">
    <a href="../index.html">
      <img border=0 alt="NumPy" src="../_static/numpy_logo.png"></a>
    </div>
  </div>
</div>


    <div class="container">
      <div class="main">
        
	<div class="row-fluid">
	  <div class="span12">
	    <div class="spc-navbar">
              
    <ul class="nav nav-pills pull-left">
        <li class="active"><a href="https://numpy.org/">NumPy.org</a></li>
        <li class="active"><a href="https://numpy.org/doc">Docs</a></li>
        
        <li class="active"><a href="../index.html">NumPy v1.18 Manual</a></li>
        

          <li class="active"><a href="index.html" accesskey="U">NumPy’s Documentation</a></li> 
    </ul>
              
              
    <ul class="nav nav-pills pull-right">
      <li class="active">
        <a href="../genindex.html" title="General Index"
           accesskey="I">index</a>
      </li>
      <li class="active">
        <a href="howto_build_docs.html" title="Building the NumPy API and reference docs"
           accesskey="N">next</a>
      </li>
      <li class="active">
        <a href="index.html" title="NumPy’s Documentation"
           accesskey="P">previous</a>
      </li>
    </ul>
              
	    </div>
	  </div>
	</div>
        

	<div class="row-fluid">
      <div class="spc-rightsidebar span3">
        <div class="sphinxsidebarwrapper">
  <h3><a href="../contents.html">Table of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">A Guide to NumPy/SciPy Documentation</a><ul>
<li><a class="reference internal" href="#numpydoc-docstring-guide">numpydoc docstring guide</a><ul>
<li><a class="reference internal" href="#overview">Overview</a></li>
<li><a class="reference internal" href="#import-conventions">Import conventions</a></li>
<li><a class="reference internal" href="#docstring-standard">Docstring Standard</a></li>
<li><a class="reference internal" href="#sections">Sections</a></li>
<li><a class="reference internal" href="#documenting-classes">Documenting classes</a><ul>
<li><a class="reference internal" href="#class-docstring">Class docstring</a></li>
<li><a class="reference internal" href="#method-docstrings">Method docstrings</a></li>
</ul>
</li>
<li><a class="reference internal" href="#documenting-class-instances">Documenting class instances</a></li>
<li><a class="reference internal" href="#documenting-generators">Documenting generators</a></li>
<li><a class="reference internal" href="#documenting-constants">Documenting constants</a></li>
<li><a class="reference internal" href="#documenting-modules">Documenting modules</a></li>
<li><a class="reference internal" href="#other-points-to-keep-in-mind">Other points to keep in mind</a></li>
<li><a class="reference internal" href="#common-rest-concepts">Common reST concepts</a></li>
<li><a class="reference internal" href="#conclusion">Conclusion</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#example-source">Example Source</a></li>
<li><a class="reference internal" href="#example-rendered">Example Rendered</a></li>
</ul>

  <h4>Previous topic</h4>
  <p class="topless"><a href="index.html"
                        title="previous chapter">NumPy’s Documentation</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="howto_build_docs.html"
                        title="next chapter">Building the NumPy API and reference docs</a></p>
<div id="searchbox" style="display: none" role="search">
  <h4>Quick search</h4>
    <div>
    <form class="search" action="../search.html" method="get">
      <input type="text" style="width: inherit;" name="q" />
      <input type="submit" value="search" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    </div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
          <div class="span9">
            
        <div class="bodywrapper">
          <div class="body" id="spc-section-body">
            
  <div class="section" id="a-guide-to-numpy-scipy-documentation">
<span id="howto-document"></span><h1><a class="toc-backref" href="#id6">A Guide to NumPy/SciPy Documentation</a><a class="headerlink" href="#a-guide-to-numpy-scipy-documentation" title="Permalink to this headline">¶</a></h1>
<p>When using <a class="reference external" href="http://www.sphinx-doc.org/">Sphinx</a> in combination with the
numpy conventions, you should use the <code class="docutils literal notranslate"><span class="pre">numpydoc</span></code> extension so that your
docstrings will be handled correctly. For example, Sphinx will extract the
<code class="docutils literal notranslate"><span class="pre">Parameters</span></code> section from your docstring and convert it into a field
list.  Using <code class="docutils literal notranslate"><span class="pre">numpydoc</span></code> will also avoid the reStructuredText errors produced
by plain Sphinx when it encounters numpy docstring conventions like
section headers (e.g. <code class="docutils literal notranslate"><span class="pre">-------------</span></code>) that sphinx does not expect to
find in docstrings.</p>
<p>Some features described in this document require a recent version of
<code class="docutils literal notranslate"><span class="pre">numpydoc</span></code>. For example, the <strong>Yields</strong> section was added in
<code class="docutils literal notranslate"><span class="pre">numpydoc</span></code> 0.6.</p>
<p>It is available from:</p>
<ul class="simple">
<li><p><a class="reference external" href="https://pypi.python.org/pypi/numpydoc">numpydoc on PyPI</a></p></li>
<li><p><a class="reference external" href="https://github.com/numpy/numpydoc/">numpydoc on GitHub</a></p></li>
</ul>
<p>Note that for documentation within numpy, it is not necessary to do
<code class="docutils literal notranslate"><span class="pre">import</span> <span class="pre">numpy</span> <span class="pre">as</span> <span class="pre">np</span></code> at the beginning of an example.  However, some
sub-modules, such as <code class="docutils literal notranslate"><span class="pre">fft</span></code>, are not imported by default, and you have to
include them explicitly:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">numpy.fft</span>
</pre></div>
</div>
<p>after which you may use it:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">np</span><span class="o">.</span><span class="n">fft</span><span class="o">.</span><span class="n">fft2</span><span class="p">(</span><span class="o">...</span><span class="p">)</span>
</pre></div>
</div>
<p class="rubric"><strong>For convenience the</strong> <a class="reference external" href="https://numpydoc.readthedocs.io/en/latest/format.html">formatting standard</a> <strong>is included below with an
example</strong></p>
<div class="section" id="numpydoc-docstring-guide">
<span id="format"></span><h2><a class="toc-backref" href="#id7">numpydoc docstring guide</a><a class="headerlink" href="#numpydoc-docstring-guide" title="Permalink to this headline">¶</a></h2>
<div class="contents topic" id="contents">
<p class="topic-title">Contents</p>
<ul class="simple">
<li><p><a class="reference internal" href="#a-guide-to-numpy-scipy-documentation" id="id6">A Guide to NumPy/SciPy Documentation</a></p>
<ul>
<li><p><a class="reference internal" href="#numpydoc-docstring-guide" id="id7">numpydoc docstring guide</a></p>
<ul>
<li><p><a class="reference internal" href="#overview" id="id8">Overview</a></p></li>
<li><p><a class="reference internal" href="#import-conventions" id="id9">Import conventions</a></p></li>
<li><p><a class="reference internal" href="#docstring-standard" id="id10">Docstring Standard</a></p></li>
<li><p><a class="reference internal" href="#sections" id="id11">Sections</a></p></li>
<li><p><a class="reference internal" href="#documenting-classes" id="id12">Documenting classes</a></p>
<ul>
<li><p><a class="reference internal" href="#class-docstring" id="id13">Class docstring</a></p></li>
<li><p><a class="reference internal" href="#method-docstrings" id="id14">Method docstrings</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#documenting-class-instances" id="id15">Documenting class instances</a></p></li>
<li><p><a class="reference internal" href="#documenting-generators" id="id16">Documenting generators</a></p></li>
<li><p><a class="reference internal" href="#documenting-constants" id="id17">Documenting constants</a></p></li>
<li><p><a class="reference internal" href="#documenting-modules" id="id18">Documenting modules</a></p></li>
<li><p><a class="reference internal" href="#other-points-to-keep-in-mind" id="id19">Other points to keep in mind</a></p></li>
<li><p><a class="reference internal" href="#common-rest-concepts" id="id20">Common reST concepts</a></p></li>
<li><p><a class="reference internal" href="#conclusion" id="id21">Conclusion</a></p></li>
</ul>
</li>
</ul>
</li>
<li><p><a class="reference internal" href="#example-source" id="id22">Example Source</a></p></li>
<li><p><a class="reference internal" href="#example-rendered" id="id23">Example Rendered</a></p></li>
</ul>
</div>
<p>This document describes the syntax and best practices for docstrings used with
the numpydoc extension for <a class="reference external" href="http://sphinx-doc.org/">Sphinx</a>.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>For an accompanying example, see <a class="reference internal" href="#example"><span class="std std-ref">example.py</span></a>.</p>
<p>Some features described in this document require a recent version of
<code class="docutils literal notranslate"><span class="pre">numpydoc</span></code>. For example, the <strong>Yields</strong> section was added in
<code class="docutils literal notranslate"><span class="pre">numpydoc</span></code> 0.6.</p>
</div>
<div class="section" id="overview">
<h3><a class="toc-backref" href="#id8">Overview</a><a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h3>
<dl class="simple">
<dt>We mostly follow the standard Python style conventions as described here:</dt><dd><ul class="simple">
<li><p><a class="reference external" href="http://python.org/dev/peps/pep-0007/">Style Guide for C Code</a></p></li>
<li><p><a class="reference external" href="http://python.org/dev/peps/pep-0008/">Style Guide for Python Code</a></p></li>
<li><p><a class="reference external" href="http://python.org/dev/peps/pep-0257/">Docstring Conventions</a></p></li>
</ul>
</dd>
<dt>Additional PEPs of interest regarding documentation of code:</dt><dd><ul class="simple">
<li><p><a class="reference external" href="http://python.org/dev/peps/pep-0256/">Docstring Processing Framework</a></p></li>
<li><p><a class="reference external" href="http://python.org/dev/peps/pep-0258/">Docutils Design Specification</a></p></li>
</ul>
</dd>
<dt>Use a code checker:</dt><dd><ul class="simple">
<li><p><a class="reference external" href="http://www.logilab.org/857">pylint</a></p></li>
<li><p><a class="reference external" href="https://pypi.python.org/pypi/pyflakes">pyflakes</a></p></li>
<li><p><a class="reference external" href="http://svn.browsershots.org/trunk/devtools/pep8/pep8.py">pep8.py</a></p></li>
<li><p><a class="reference external" href="https://pypi.python.org/pypi/flake8">flake8</a></p></li>
<li><p><a class="reference external" href="https://github.com/nvie/vim-flake8">vim-flake8</a> plugin for
automatically checking syntax and style with flake8</p></li>
</ul>
</dd>
</dl>
</div>
<div class="section" id="import-conventions">
<h3><a class="toc-backref" href="#id9">Import conventions</a><a class="headerlink" href="#import-conventions" title="Permalink to this headline">¶</a></h3>
<p>The following import conventions are used throughout the NumPy source
and documentation:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">numpy</span> <span class="k">as</span> <span class="nn">np</span>
<span class="kn">import</span> <span class="nn">matplotlib</span> <span class="k">as</span> <span class="nn">mpl</span>
<span class="kn">import</span> <span class="nn">matplotlib.pyplot</span> <span class="k">as</span> <span class="nn">plt</span>
</pre></div>
</div>
<p>Do not abbreviate <code class="docutils literal notranslate"><span class="pre">scipy</span></code>. There is no motivating use case to
abbreviate it in the real world, so we avoid it in the documentation
to avoid confusion.</p>
</div>
<div class="section" id="docstring-standard">
<h3><a class="toc-backref" href="#id10">Docstring Standard</a><a class="headerlink" href="#docstring-standard" title="Permalink to this headline">¶</a></h3>
<p>A documentation string (docstring) is a string that describes a module,
function, class, or method definition.  The docstring is a special attribute
of the object (<code class="docutils literal notranslate"><span class="pre">object.__doc__</span></code>) and, for consistency, is surrounded by
triple double quotes, i.e.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="sd">&quot;&quot;&quot;This is the form of a docstring.</span>

<span class="sd">It can be spread over several lines.</span>

<span class="sd">&quot;&quot;&quot;</span>
</pre></div>
</div>
<p>NumPy, <a class="reference external" href="http://www.scipy.org">SciPy</a>, and the scikits follow a common convention for
docstrings that provides for consistency, while also allowing our
toolchain to produce well-formatted reference guides.  This document
describes the current community consensus for such a standard.  If you
have suggestions for improvements, post them on the <a class="reference external" href="http://scipy.org/scipylib/mailing-lists.html">numpy-discussion
list</a>.</p>
<p>Our docstring standard uses <a class="reference external" href="http://docutils.sourceforge.net/rst.html">re-structured text (reST)</a> syntax and is rendered
using <a class="reference external" href="http://sphinx.pocoo.org">Sphinx</a> (a pre-processor that understands the particular
documentation style we are using).  While a rich set of
markup is available, we limit ourselves to a very basic subset, in
order to provide docstrings that are easy to read on text-only
terminals.</p>
<p>A guiding principle is that human readers of the text are given
precedence over contorting docstrings so our tools produce nice
output.  Rather than sacrificing the readability of the docstrings, we
have written pre-processors to assist <a class="reference external" href="http://sphinx.pocoo.org">Sphinx</a> in its task.</p>
<p>The length of docstring lines should be kept to 75 characters to
facilitate reading the docstrings in text terminals.</p>
</div>
<div class="section" id="sections">
<h3><a class="toc-backref" href="#id11">Sections</a><a class="headerlink" href="#sections" title="Permalink to this headline">¶</a></h3>
<p>The docstring consists of a number of sections separated by headings (except
for the deprecation warning). Each heading should be underlined in hyphens, and
the section ordering should be consistent with the description below.</p>
<p>The sections of a function’s docstring are:</p>
<ol class="arabic">
<li><p><strong>Short summary</strong></p>
<p>A one-line summary that does not use variable names or the function
name, e.g.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">add</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">):</span>
   <span class="sd">&quot;&quot;&quot;The sum of two numbers.</span>

<span class="sd">   &quot;&quot;&quot;</span>
</pre></div>
</div>
<p>The function signature is normally found by introspection and
displayed by the help function.  For some functions (notably those
written in C) the signature is not available, so we have to specify
it as the first line of the docstring:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="sd">&quot;&quot;&quot;</span>
<span class="sd">add(a, b)</span>

<span class="sd">The sum of two numbers.</span>

<span class="sd">&quot;&quot;&quot;</span>
</pre></div>
</div>
</li>
</ol>
<ol class="arabic" start="2">
<li><p><strong>Deprecation warning</strong></p>
<p>A section (use if applicable) to warn users that the object is deprecated.
Section contents should include:</p>
<ul class="simple">
<li><p>In what NumPy version the object was deprecated, and when it will be
removed.</p></li>
<li><p>Reason for deprecation if this is useful information (e.g., object
is superseded, duplicates functionality found elsewhere, etc.).</p></li>
<li><p>New recommended way of obtaining the same functionality.</p></li>
</ul>
<p>This section should use the <code class="docutils literal notranslate"><span class="pre">deprecated</span></code> Sphinx directive instead of an
underlined section header.</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">deprecated</span><span class="p">::</span> 1.6.0
          <span class="nv">`ndobj_old`</span> will be removed in NumPy 2.0.0, it is replaced by
          <span class="nv">`ndobj_new`</span> because the latter works also with array subclasses.
</pre></div>
</div>
</li>
<li><p><strong>Extended Summary</strong></p>
<p>A few sentences giving an extended description.  This section
should be used to clarify <em>functionality</em>, not to discuss
implementation detail or background theory, which should rather be
explored in the <strong>Notes</strong> section below.  You may refer to the
parameters and the function name, but parameter descriptions still
belong in the <strong>Parameters</strong> section.</p>
</li>
<li><p><strong>Parameters</strong></p>
<p>Description of the function arguments, keywords and their
respective types.</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="gh">Parameters</span>
<span class="gh">----------</span>
x : type
    Description of parameter <span class="nv">`x`</span>.
y
    Description of parameter <span class="nv">`y`</span> (with type not specified)
</pre></div>
</div>
<p>Enclose variables in single backticks.  The colon must be preceded
by a space, or omitted if the type is absent.</p>
<p>For the parameter types, be as precise as possible.  Below are a
few examples of parameters and their types.</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="gh">Parameters</span>
<span class="gh">----------</span>
filename : str
copy : bool
dtype : data-type
iterable : iterable object
shape : int or tuple of int
files : list of str
</pre></div>
</div>
<p>If it is not necessary to specify a keyword argument, use
<code class="docutils literal notranslate"><span class="pre">optional</span></code>:</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span>x : int, optional
</pre></div>
</div>
<p>Optional keyword parameters have default values, which are
displayed as part of the function signature.  They can also be
detailed in the description:</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span>Description of parameter <span class="nv">`x`</span> (the default is -1, which implies summation
over all axes).
</pre></div>
</div>
<p>When a parameter can only assume one of a fixed set of values,
those values can be listed in braces, with the default appearing first:</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span>order : {&#39;C&#39;, &#39;F&#39;, &#39;A&#39;}
    Description of <span class="nv">`order`</span>.
</pre></div>
</div>
<p>When two or more input parameters have exactly the same type, shape and
description, they can be combined:</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span>x1, x2 : array_like
    Input arrays, description of <span class="nv">`x1`</span>, <span class="nv">`x2`</span>.
</pre></div>
</div>
</li>
<li><p><strong>Returns</strong></p>
<p>Explanation of the returned values and their types. Similar to the
<strong>Parameters</strong> section, except the name of each return value is optional.
The type of each return value is always required:</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="gh">Returns</span>
<span class="gh">-------</span>
int
    Description of anonymous integer return value.
</pre></div>
</div>
<p>If both the name and type are specified, the <strong>Returns</strong> section takes the
same form as the <strong>Parameters</strong> section:</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="gh">Returns</span>
<span class="gh">-------</span>
err_code : int
    Non-zero value indicates error code, or zero on success.
err_msg : str or None
    Human readable error message, or None on success.
</pre></div>
</div>
</li>
<li><p><strong>Yields</strong></p>
<p>Explanation of the yielded values and their types. This is relevant to
generators only. Similar to the <strong>Returns</strong> section in that the name of
each value is optional, but the type of each value is always required:</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="gh">Yields</span>
<span class="gh">------</span>
int
    Description of the anonymous integer return value.
</pre></div>
</div>
<p>If both the name and type are specified, the <strong>Yields</strong> section takes the
same form as the <strong>Returns</strong> section:</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="gh">Yields</span>
<span class="gh">------</span>
err_code : int
    Non-zero value indicates error code, or zero on success.
err_msg : str or None
    Human readable error message, or None on success.
</pre></div>
</div>
<p>Support for the <strong>Yields</strong> section was added in <a class="reference external" href="https://github.com/numpy/numpydoc">numpydoc</a> version 0.6.</p>
</li>
<li><p><strong>Receives</strong></p>
<p>Explanation of parameters passed to a generator’s <code class="docutils literal notranslate"><span class="pre">.send()</span></code> method,
formatted as for Parameters, above.  Since, like for Yields and Returns, a
single object is always passed to the method, this may describe either the
single parameter, or positional arguments passed as a tuple.  If a docstring
includes Receives it must also include Yields.</p>
</li>
<li><p><strong>Other Parameters</strong></p>
<p>An optional section used to describe infrequently used parameters.
It should only be used if a function has a large number of keyword
parameters, to prevent cluttering the <strong>Parameters</strong> section.</p>
</li>
<li><p><strong>Raises</strong></p>
<p>An optional section detailing which errors get raised and under
what conditions:</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="gh">Raises</span>
<span class="gh">------</span>
LinAlgException
    If the matrix is not numerically invertible.
</pre></div>
</div>
<p>This section should be used judiciously, i.e., only for errors
that are non-obvious or have a large chance of getting raised.</p>
</li>
<li><p><strong>Warns</strong></p></li>
</ol>
<blockquote>
<div><p>An optional section detailing which warnings get raised and
under what conditions, formatted similarly to Raises.</p>
</div></blockquote>
<ol class="arabic" start="11">
<li><p><strong>Warnings</strong></p>
<p>An optional section with cautions to the user in free text/reST.</p>
</li>
<li><p><strong>See Also</strong></p>
<p>An optional section used to refer to related code.  This section
can be very useful, but should be used judiciously.  The goal is to
direct users to other functions they may not be aware of, or have
easy means of discovering (by looking at the module docstring, for
example).  Routines whose docstrings further explain parameters
used by this function are good candidates.</p>
<p>As an example, for <code class="docutils literal notranslate"><span class="pre">numpy.mean</span></code> we would have:</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="gh">See Also</span>
<span class="gh">--------</span>
average : Weighted average
</pre></div>
</div>
<p>When referring to functions in the same sub-module, no prefix is
needed, and the tree is searched upwards for a match.</p>
<p>Prefix functions from other sub-modules appropriately.  E.g.,
whilst documenting the <code class="docutils literal notranslate"><span class="pre">random</span></code> module, refer to a function in
<code class="docutils literal notranslate"><span class="pre">fft</span></code> by</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span>fft.fft2 : 2-D fast discrete Fourier transform
</pre></div>
</div>
<p>When referring to an entirely different module:</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span>scipy.random.norm : Random variates, PDFs, etc.
</pre></div>
</div>
<p>Functions may be listed without descriptions, and this is
preferable if the functionality is clear from the function name:</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="gh">See Also</span>
<span class="gh">--------</span>
func_a : Function a with its description.
func_b, func_c_, func_d
func_e
</pre></div>
</div>
</li>
<li><p><strong>Notes</strong></p>
<p>An optional section that provides additional information about the
code, possibly including a discussion of the algorithm. This
section may include mathematical equations, written in
<a class="reference external" href="http://www.latex-project.org/">LaTeX</a> format:</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span>The FFT is a fast implementation of the discrete Fourier transform:

<span class="p">..</span> <span class="ow">math</span><span class="p">::</span> X(e^{j\omega } ) = x(n)e^{ - j\omega n}
</pre></div>
</div>
<p>Equations can also be typeset underneath the math directive:</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span>The discrete-time Fourier time-convolution property states that

<span class="p">..</span> <span class="ow">math</span><span class="p">::</span>

     x(n) * y(n) \Leftrightarrow X(e^{j\omega } )Y(e^{j\omega } )\\
     another equation here
</pre></div>
</div>
<p>Math can furthermore be used inline, i.e.</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span>The value of <span class="na">:math:</span><span class="nv">`\omega`</span> is larger than 5.
</pre></div>
</div>
<p>Variable names are displayed in typewriter font, obtained by using
<code class="docutils literal notranslate"><span class="pre">\mathtt{var}</span></code>:</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span>We square the input parameter <span class="nv">`alpha`</span> to obtain
<span class="na">:math:</span><span class="nv">`\mathtt{alpha}^2`</span>.
</pre></div>
</div>
<p>Note that LaTeX is not particularly easy to read, so use equations
sparingly.</p>
<p>Images are allowed, but should not be central to the explanation;
users viewing the docstring as text must be able to comprehend its
meaning without resorting to an image viewer.  These additional
illustrations are included using:</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">image</span><span class="p">::</span> filename
</pre></div>
</div>
<p>where filename is a path relative to the reference guide source
directory.</p>
</li>
<li><p><strong>References</strong></p>
<p>References cited in the <strong>notes</strong> section may be listed here,
e.g. if you cited the article below using the text <code class="docutils literal notranslate"><span class="pre">[1]_</span></code>,
include it as in the list as follows:</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="nt">[1]</span> O. McNoleg, &quot;The integration of GIS, remote sensing,
   expert systems and adaptive co-kriging for environmental habitat
   modelling of the Highland Haggis using object-oriented, fuzzy-logic
   and neural-network techniques,&quot; Computers &amp; Geosciences, vol. 22,
   pp. 585-588, 1996.
</pre></div>
</div>
<p>which renders as <a class="footnote-reference brackets" href="#id2" id="id1">1</a>:</p>
<dl class="footnote brackets">
<dt class="label" id="id2"><span class="brackets"><a class="fn-backref" href="#id1">1</a></span></dt>
<dd><p>O. McNoleg, “The integration of GIS, remote sensing,
expert systems and adaptive co-kriging for environmental habitat
modelling of the Highland Haggis using object-oriented, fuzzy-logic
and neural-network techniques,” Computers &amp; Geosciences, vol. 22,
pp. 585-588, 1996.</p>
</dd>
</dl>
<p>Referencing sources of a temporary nature, like web pages, is
discouraged.  References are meant to augment the docstring, but
should not be required to understand it.  References are numbered, starting
from one, in the order in which they are cited.</p>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p><strong>References will break tables</strong></p>
<p>Where references like [1] appear in a tables within a numpydoc
docstring, the table markup will be broken by numpydoc processing.  See
<a class="reference external" href="https://github.com/numpy/numpydoc/issues/130">numpydoc issue #130</a></p>
</div>
</li>
</ol>
<ol class="arabic" start="15">
<li><p><strong>Examples</strong></p>
<p>An optional section for examples, using the <a class="reference external" href="http://docs.python.org/library/doctest.html">doctest</a> format.
This section is meant to illustrate usage, not to provide a
testing framework – for that, use the <code class="docutils literal notranslate"><span class="pre">tests/</span></code> directory.
While optional, this section is very strongly encouraged.</p>
<p>When multiple examples are provided, they should be separated by
blank lines. Comments explaining the examples should have blank
lines both above and below them:</p>
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">)</span>
<span class="go">3</span>

<span class="go">Comment explaining the second example</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">add</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">],</span> <span class="p">[</span><span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">])</span>
<span class="go">array([4, 6])</span>
</pre></div>
</div>
<p>The example code may be split across multiple lines, with each line after
the first starting with ‘… ‘:</p>
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">add</span><span class="p">([[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">],</span> <span class="p">[</span><span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">]],</span>
<span class="gp">... </span>       <span class="p">[[</span><span class="mi">5</span><span class="p">,</span> <span class="mi">6</span><span class="p">],</span> <span class="p">[</span><span class="mi">7</span><span class="p">,</span> <span class="mi">8</span><span class="p">]])</span>
<span class="go">array([[ 6,  8],</span>
<span class="go">       [10, 12]])</span>
</pre></div>
</div>
<p>For tests with a result that is random or platform-dependent, mark the
output as such:</p>
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">numpy.random</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">random</span><span class="o">.</span><span class="n">rand</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span>
<span class="go">array([ 0.35773152,  0.38568979])  #random</span>
</pre></div>
</div>
<p>You can run examples as doctests using:</p>
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">test</span><span class="p">(</span><span class="n">doctests</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">linalg</span><span class="o">.</span><span class="n">test</span><span class="p">(</span><span class="n">doctests</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>  <span class="c1"># for a single module</span>
</pre></div>
</div>
<p>In IPython it is also possible to run individual examples simply by
copy-pasting them in doctest mode:</p>
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="go">In [1]: %doctest_mode</span>
<span class="go">Exception reporting mode: Plain</span>
<span class="go">Doctest mode is: ON</span>
<span class="gp">&gt;&gt;&gt; </span><span class="o">%</span><span class="n">paste</span>
<span class="go"> import numpy.random</span>
<span class="go"> np.random.rand(2)</span>
<span class="go">## -- End pasted text --</span>
<span class="go">array([ 0.8519522 ,  0.15492887])</span>
</pre></div>
</div>
<p>It is not necessary to use the doctest markup <code class="docutils literal notranslate"><span class="pre">&lt;BLANKLINE&gt;</span></code> to
indicate empty lines in the output. Note that the option to run
the examples through <code class="docutils literal notranslate"><span class="pre">numpy.test</span></code> is provided for checking if the
examples work, not for making the examples part of the testing framework.</p>
<p>The examples may assume that <code class="docutils literal notranslate"><span class="pre">import</span> <span class="pre">numpy</span> <span class="pre">as</span> <span class="pre">np</span></code> is executed before
the example code in <em>numpy</em>. Additional examples may make use of
<em>matplotlib</em> for plotting, but should import it explicitly, e.g.,
<code class="docutils literal notranslate"><span class="pre">import</span> <span class="pre">matplotlib.pyplot</span> <span class="pre">as</span> <span class="pre">plt</span></code>. All other imports, including the
demonstrated function, must be explicit.</p>
<p>When matplotlib is imported in the example, the Example code will be
wrapped in <em class="xref py py-obj">matplotlib’s Sphinx `plot</em> directive
&lt;<a class="reference external" href="http://matplotlib.org/sampledoc/extensions.html">http://matplotlib.org/sampledoc/extensions.html</a>&gt;`_.  When matplotlib is
not explicitly imported, <em class="xref py py-obj"> plot::</em> can be used directly if
<a class="reference external" href="https://matplotlib.org/devel/plot_directive.html#module-matplotlib.sphinxext.plot_directive" title="(in Matplotlib v3.1.3)"><code class="xref py py-obj docutils literal notranslate"><span class="pre">matplotlib.sphinxext.plot_directive</span></code></a> is loaded as a Sphinx extension in
<code class="docutils literal notranslate"><span class="pre">conf.py</span></code>.</p>
</li>
</ol>
</div>
<div class="section" id="documenting-classes">
<h3><a class="toc-backref" href="#id12">Documenting classes</a><a class="headerlink" href="#documenting-classes" title="Permalink to this headline">¶</a></h3>
<div class="section" id="class-docstring">
<h4><a class="toc-backref" href="#id13">Class docstring</a><a class="headerlink" href="#class-docstring" title="Permalink to this headline">¶</a></h4>
<p>Use the same sections as outlined above (all except <code class="docutils literal notranslate"><span class="pre">Returns</span></code> are
applicable).  The constructor (<code class="docutils literal notranslate"><span class="pre">__init__</span></code>) should also be documented
here, the <strong>Parameters</strong> section of the docstring details the constructors
parameters.</p>
<p>An <strong>Attributes</strong> section, located below the <strong>Parameters</strong> section,
may be used to describe non-method attributes of the class:</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="gh">Attributes</span>
<span class="gh">----------</span>
x : float
    The X coordinate.
y : float
    The Y coordinate.
</pre></div>
</div>
<p>Attributes that are properties and have their own docstrings can be
simply listed by name:</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="gh">Attributes</span>
<span class="gh">----------</span>
real
imag
x : float
    The X coordinate
y : float
    The Y coordinate
</pre></div>
</div>
<p>In general, it is not necessary to list class methods.  Those that are
not part of the public API have names that start with an underscore.
In some cases, however, a class may have a great many methods, of
which only a few are relevant (e.g., subclasses of ndarray).  Then, it
becomes useful to have an additional <strong>Methods</strong> section:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Photo</span><span class="p">(</span><span class="n">ndarray</span><span class="p">):</span>
    <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">    Array with associated photographic information.</span>

<span class="sd">    ...</span>

<span class="sd">    Attributes</span>
<span class="sd">    ----------</span>
<span class="sd">    exposure : float</span>
<span class="sd">        Exposure in seconds.</span>

<span class="sd">    Methods</span>
<span class="sd">    -------</span>
<span class="sd">    colorspace(c=&#39;rgb&#39;)</span>
<span class="sd">        Represent the photo in the given colorspace.</span>
<span class="sd">    gamma(n=1.0)</span>
<span class="sd">        Change the photo&#39;s gamma exposure.</span>

<span class="sd">    &quot;&quot;&quot;</span>
</pre></div>
</div>
<p>If it is necessary to explain a private method (use with care!), it can
be referred to in the <strong>Extended Summary</strong> or the <strong>Notes</strong> section.
Do not list private methods in the <strong>methods</strong> section.</p>
<p>Note that <em class="xref py py-obj">self</em> is <em>not</em> listed as the first parameter of methods.</p>
</div>
<div class="section" id="method-docstrings">
<h4><a class="toc-backref" href="#id14">Method docstrings</a><a class="headerlink" href="#method-docstrings" title="Permalink to this headline">¶</a></h4>
<p>Document these as you would any other function.  Do not include
<code class="docutils literal notranslate"><span class="pre">self</span></code> in the list of parameters.  If a method has an equivalent function
(which is the case for many ndarray methods for example), the function
docstring should contain the detailed documentation, and the method docstring
should refer to it.  Only put brief summary and <strong>See Also</strong> sections in the
method docstring. The method should use a <strong>Returns</strong> or <strong>Yields</strong> section,
as appropriate.</p>
</div>
</div>
<div class="section" id="documenting-class-instances">
<h3><a class="toc-backref" href="#id15">Documenting class instances</a><a class="headerlink" href="#documenting-class-instances" title="Permalink to this headline">¶</a></h3>
<p>Instances of classes that are part of the NumPy API (for example <em class="xref py py-obj">np.r_</em>
<em class="xref py py-obj">np,c_</em>, <em class="xref py py-obj">np.index_exp</em>, etc.) may require some care. To give these
instances a useful docstring, we do the following:</p>
<ul class="simple">
<li><p>Single instance: If only a single instance of a class is exposed,
document the class. Examples can use the instance name.</p></li>
<li><p>Multiple instances: If multiple instances are exposed, docstrings
for each instance are written and assigned to the instances’
<code class="docutils literal notranslate"><span class="pre">__doc__</span></code> attributes at run time. The class is documented as usual, and
the exposed instances can be mentioned in the <strong>Notes</strong> and <strong>See Also</strong>
sections.</p></li>
</ul>
</div>
<div class="section" id="documenting-generators">
<h3><a class="toc-backref" href="#id16">Documenting generators</a><a class="headerlink" href="#documenting-generators" title="Permalink to this headline">¶</a></h3>
<p>Generators should be documented just as functions are documented. The
only difference is that one should use the <strong>Yields</strong> section instead
of the <strong>Returns</strong> section. Support for the <strong>Yields</strong> section was added in
<a class="reference external" href="https://github.com/numpy/numpydoc">numpydoc</a> version 0.6.</p>
</div>
<div class="section" id="documenting-constants">
<h3><a class="toc-backref" href="#id17">Documenting constants</a><a class="headerlink" href="#documenting-constants" title="Permalink to this headline">¶</a></h3>
<p>Use the same sections as outlined for functions where applicable:</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="m">1.</span> summary
<span class="m">2.</span> extended summary (optional)
<span class="m">3.</span> see also (optional)
<span class="m">4.</span> references (optional)
<span class="m">5.</span> examples (optional)
</pre></div>
</div>
<p>Docstrings for constants will not be visible in text terminals
(constants are of immutable type, so docstrings can not be assigned
to them like for for class instances), but will appear in the
documentation built with Sphinx.</p>
</div>
<div class="section" id="documenting-modules">
<h3><a class="toc-backref" href="#id18">Documenting modules</a><a class="headerlink" href="#documenting-modules" title="Permalink to this headline">¶</a></h3>
<p>Each module should have a docstring with at least a summary line. Other
sections are optional, and should be used in the same order as for documenting
functions when they are appropriate:</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="m">1.</span> summary
<span class="m">2.</span> extended summary
<span class="m">3.</span> routine listings
<span class="m">4.</span> see also
<span class="m">5.</span> notes
<span class="m">6.</span> references
<span class="m">7.</span> examples
</pre></div>
</div>
<p>Routine listings are encouraged, especially for large modules, for which it is
hard to get a good overview of all functionality provided by looking at the
source file(s) or the <code class="docutils literal notranslate"><span class="pre">__all__</span></code> dict.</p>
<p>Note that license and author info, while often included in source files, do not
belong in docstrings.</p>
</div>
<div class="section" id="other-points-to-keep-in-mind">
<h3><a class="toc-backref" href="#id19">Other points to keep in mind</a><a class="headerlink" href="#other-points-to-keep-in-mind" title="Permalink to this headline">¶</a></h3>
<ul>
<li><p>Equations : as discussed in the <strong>Notes</strong> section above, LaTeX formatting
should be kept to a minimum.  Often it’s possible to show equations as
Python code or pseudo-code instead, which is much more readable in a
terminal.  For inline display use double backticks (like <code class="docutils literal notranslate"><span class="pre">y</span> <span class="pre">=</span> <span class="pre">np.sin(x)</span></code>).
For display with blank lines above and below, use a double colon and indent
the code, like:</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span>end of previous sentence::

    y = np.sin(x)
</pre></div>
</div>
</li>
<li><p>Notes and Warnings : If there are points in the docstring that deserve
special emphasis, the reST directives for a note or warning can be used
in the vicinity of the context of the warning (inside a section). Syntax:</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">warning</span><span class="p">::</span> Warning text.

<span class="p">..</span> <span class="ow">note</span><span class="p">::</span> Note text.
</pre></div>
</div>
<p>Use these sparingly, as they do not look very good in text terminals
and are not often necessary. One situation in which a warning can
be useful is for marking a known bug that is not yet fixed.</p>
</li>
<li><p>array_like : For functions that take arguments which can have not only
a type <em class="xref py py-obj">ndarray</em>, but also types that can be converted to an ndarray
(i.e. scalar types, sequence types), those arguments can be documented
with type <em class="xref py py-obj">array_like</em>.</p></li>
<li><p>Links : If you need to include hyperlinks in your docstring, note that
some docstring sections are not parsed as standard reST, and in these
sections, numpydoc may become confused by hyperlink targets such as:</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="nt">_Example:</span> http://www.example.com
</pre></div>
</div>
<p>If the Sphinx build issues a warning of the form
<code class="docutils literal notranslate"><span class="pre">WARNING:</span> <span class="pre">Unknown</span> <span class="pre">target</span> <span class="pre">name:</span> <span class="pre">&quot;example&quot;</span></code>, then that is what is happening.
To avoid this problem, use the inline hyperlink form:</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="s">`Example </span><span class="si">&lt;http://www.example.com&gt;</span><span class="s">`_</span>
</pre></div>
</div>
</li>
</ul>
</div>
<div class="section" id="common-rest-concepts">
<h3><a class="toc-backref" href="#id20">Common reST concepts</a><a class="headerlink" href="#common-rest-concepts" title="Permalink to this headline">¶</a></h3>
<p>For paragraphs, indentation is significant and indicates indentation in the
output. New paragraphs are marked with a blank line.</p>
<p>Use <code class="docutils literal notranslate"><span class="pre">*italics*</span></code>, <code class="docutils literal notranslate"><span class="pre">**bold**</span></code> and <code class="docutils literal notranslate"><span class="pre">``monospace``</span></code> if needed in any
explanations
(but not for variable names and doctest code or multi-line code).
Variable, module, function, and class names should be written between
single back-ticks (<code class="docutils literal notranslate"><span class="pre">`numpy`</span></code>).</p>
<p>A more extensive example of reST markup can be found in <a class="reference external" href="http://docutils.sourceforge.net/docs/user/rst/demo.txt">this example
document</a>;
the <a class="reference external" href="http://docutils.sourceforge.net/docs/user/rst/quickref.html">quick reference</a> is
useful while editing.</p>
<p>Line spacing and indentation are significant and should be carefully
followed.</p>
</div>
<div class="section" id="conclusion">
<h3><a class="toc-backref" href="#id21">Conclusion</a><a class="headerlink" href="#conclusion" title="Permalink to this headline">¶</a></h3>
<p>This document itself was written in ReStructuredText.
<a class="reference internal" href="#example"><span class="std std-ref">An example</span></a> of the format shown here is available.</p>
</div>
</div>
</div>
<div class="section" id="example-source">
<span id="example"></span><h1><a class="toc-backref" href="#id22">Example Source</a><a class="headerlink" href="#example-source" title="Permalink to this headline">¶</a></h1>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span>&quot;&quot;&quot;This is the docstring for the example.py module.  Modules names should
have short, all-lowercase names.  The module name may have underscores if
this improves readability.

Every module should have a docstring at the very top of the file.  The
module&#39;s docstring may extend over multiple lines.  If your docstring does
extend over multiple lines, the closing three quotation marks must be on
a line by itself, preferably preceded by a blank line.

&quot;&quot;&quot;
from __future__ import division, absolute_import, print_function

import os  # standard library imports first

# Do NOT import using <span class="ge">*, e.g. from numpy import *</span>
<span class="gh">#</span>
<span class="gh"># Import the module using</span>
<span class="gh">#</span>
#   import numpy
<span class="gh">#</span>
<span class="gh"># instead or import individual functions as needed, e.g</span>
<span class="gh">#</span>
#  from numpy import array, zeros
#
# If you prefer the use of abbreviated module names, we suggest the
# convention used by NumPy itself::

import numpy as np
import matplotlib as mpl
import matplotlib.pyplot as plt

# These abbreviated names are not to be used in docstrings; users must
# be able to paste and execute docstrings after importing only the
# numpy module itself, unabbreviated.


def foo(var1, var2, long_var_name=&#39;hi&#39;):
    r&quot;&quot;&quot;A one-line summary that does not use variable names or the
    function name.

    Several sentences providing an extended description. Refer to
    variables using back-ticks, e.g. <span class="nv">`var`</span>.

    Parameters
    ----------
    var1 : array_like
        Array_like means all those objects -- lists, nested lists, etc. --
        that can be converted to an array.  We can also refer to
        variables like <span class="nv">`var1`</span>.
    var2 : int
        The type above can either refer to an actual Python type
        (e.g. <span class="s">``int``</span>), or describe the type of the variable in more
        detail, e.g. <span class="s">``(N,) ndarray``</span> or <span class="s">``array_like``</span>.
    long_var_name : {&#39;hi&#39;, &#39;ho&#39;}, optional
        Choices in brackets, default first when optional.

    Returns
    -------
    type
        Explanation of anonymous return value of type <span class="s">``type``</span>.
    describe : type
        Explanation of return value named <span class="nv">`describe`</span>.
    out : type
        Explanation of <span class="nv">`out`</span>.
    type_without_description

    Other Parameters
    ----------------
    only_seldom_used_keywords : type
        Explanation
    common_parameters_listed_above : type
        Explanation

    Raises
    ------
    BadException
        Because you shouldn&#39;t have done that.

    See Also
    --------
    otherfunc : relationship (optional)
    newfunc : Relationship (optional), which could be fairly long, in which
              case the line wraps here.
    thirdfunc, fourthfunc, fifthfunc

    Notes
    -----
    Notes about the implementation algorithm (if needed).

    This can have multiple paragraphs.

    You may include some math:

<span class="p">    ..</span> <span class="ow">math</span><span class="p">::</span> X(e^{j\omega } ) = x(n)e^{ - j\omega n}

    And even use a Greek symbol like <span class="na">:math:</span><span class="nv">`\omega`</span> inline.

    References
    ----------
    Cite the relevant literature, e.g. <span class="s">[1]_</span>.  You may also cite these
    references in the notes section above.

<span class="p">    ..</span> <span class="nt">[1]</span> O. McNoleg, &quot;The integration of GIS, remote sensing,
       expert systems and adaptive co-kriging for environmental habitat
       modelling of the Highland Haggis using object-oriented, fuzzy-logic
       and neural-network techniques,&quot; Computers &amp; Geosciences, vol. 22,
       pp. 585-588, 1996.

    Examples
    --------
    These are written in doctest format, and should illustrate how to
    use the function.

    &gt;&gt;&gt; a = [1, 2, 3]
    &gt;&gt;&gt; print [x + 3 for x in a]
    [4, 5, 6]
    &gt;&gt;&gt; print &quot;a\n\nb&quot;
    a
    b

    &quot;&quot;&quot;

    pass
</pre></div>
</div>
</div>
<div class="section" id="example-rendered">
<h1><a class="toc-backref" href="#id23">Example Rendered</a><a class="headerlink" href="#example-rendered" title="Permalink to this headline">¶</a></h1>
<span class="target" id="module-doc.example"></span><p>This is the docstring for the example.py module.  Modules names should
have short, all-lowercase names.  The module name may have underscores if
this improves readability.</p>
<p>Every module should have a docstring at the very top of the file.  The
module’s docstring may extend over multiple lines.  If your docstring does
extend over multiple lines, the closing three quotation marks must be on
a line by itself, preferably preceded by a blank line.</p>
<dl class="function">
<dt id="doc.example.foo">
<code class="sig-prename descclassname">doc.example.</code><code class="sig-name descname">foo</code><span class="sig-paren">(</span><em class="sig-param">var1</em>, <em class="sig-param">var2</em>, <em class="sig-param">long_var_name='hi'</em><span class="sig-paren">)</span><a class="reference external" href="https://github.com/numpy/numpy/blob/v1.18.1/numpy/../../../../../../root/numpy/doc/sphinxext/doc/example.py#L37-L123"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#doc.example.foo" title="Permalink to this definition">¶</a></dt>
<dd><p>A one-line summary that does not use variable names or the
function name.</p>
<p>Several sentences providing an extended description. Refer to
variables using back-ticks, e.g. <em class="xref py py-obj">var</em>.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><dl class="simple">
<dt><strong>var1</strong><span class="classifier">array_like</span></dt><dd><p>Array_like means all those objects – lists, nested lists, etc. –
that can be converted to an array.  We can also refer to
variables like <em class="xref py py-obj">var1</em>.</p>
</dd>
<dt><strong>var2</strong><span class="classifier">int</span></dt><dd><p>The type above can either refer to an actual Python type
(e.g. <code class="docutils literal notranslate"><span class="pre">int</span></code>), or describe the type of the variable in more
detail, e.g. <code class="docutils literal notranslate"><span class="pre">(N,)</span> <span class="pre">ndarray</span></code> or <code class="docutils literal notranslate"><span class="pre">array_like</span></code>.</p>
</dd>
<dt><strong>long_var_name</strong><span class="classifier">{‘hi’, ‘ho’}, optional</span></dt><dd><p>Choices in brackets, default first when optional.</p>
</dd>
</dl>
</dd>
<dt class="field-even">Returns</dt>
<dd class="field-even"><dl class="simple">
<dt><strong>type</strong></dt><dd><p>Explanation of anonymous return value of type <code class="docutils literal notranslate"><span class="pre">type</span></code>.</p>
</dd>
<dt><strong>describe</strong><span class="classifier">type</span></dt><dd><p>Explanation of return value named <em class="xref py py-obj">describe</em>.</p>
</dd>
<dt><strong>out</strong><span class="classifier">type</span></dt><dd><p>Explanation of <em class="xref py py-obj">out</em>.</p>
</dd>
<dt><strong>type_without_description</strong></dt><dd></dd>
</dl>
</dd>
<dt class="field-odd">Other Parameters</dt>
<dd class="field-odd"><dl class="simple">
<dt><strong>only_seldom_used_keywords</strong><span class="classifier">type</span></dt><dd><p>Explanation</p>
</dd>
<dt><strong>common_parameters_listed_above</strong><span class="classifier">type</span></dt><dd><p>Explanation</p>
</dd>
</dl>
</dd>
<dt class="field-even">Raises</dt>
<dd class="field-even"><dl class="simple">
<dt><strong>BadException</strong></dt><dd><p>Because you shouldn’t have done that.</p>
</dd>
</dl>
</dd>
</dl>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<dl class="simple">
<dt><code class="xref py py-obj docutils literal notranslate"><span class="pre">otherfunc</span></code></dt><dd><p>relationship (optional)</p>
</dd>
<dt><code class="xref py py-obj docutils literal notranslate"><span class="pre">newfunc</span></code></dt><dd><p>Relationship (optional), which could be fairly long, in which case the line wraps here.</p>
</dd>
</dl>
<p><code class="xref py py-obj docutils literal notranslate"><span class="pre">thirdfunc</span></code>, <code class="xref py py-obj docutils literal notranslate"><span class="pre">fourthfunc</span></code>, <code class="xref py py-obj docutils literal notranslate"><span class="pre">fifthfunc</span></code></p>
</div>
<p class="rubric">Notes</p>
<p>Notes about the implementation algorithm (if needed).</p>
<p>This can have multiple paragraphs.</p>
<p>You may include some math:</p>
<div class="math">
<p><img src="../_images/math/92b9a07abae48c7e4bf2e04d9ae639389fa72307.svg" alt="X(e^{j\omega } ) = x(n)e^{ - j\omega n}"/></p>
</div><p>And even use a Greek symbol like <img class="math" src="../_images/math/16cb1e006199f0853a2dc67ea814446a38beb54e.svg" alt="\omega"/> inline.</p>
<p class="rubric">References</p>
<p>Cite the relevant literature, e.g. <a class="reference internal" href="#ree6d1ec14498-1" id="id4">[1]</a>.  You may also cite these
references in the notes section above.</p>
<dl class="citation">
<dt class="label" id="ree6d1ec14498-1"><span class="brackets"><a class="fn-backref" href="#id4">1</a></span></dt>
<dd><p>O. McNoleg, “The integration of GIS, remote sensing,
expert systems and adaptive co-kriging for environmental habitat
modelling of the Highland Haggis using object-oriented, fuzzy-logic
and neural-network techniques,” Computers &amp; Geosciences, vol. 22,
pp. 585-588, 1996.</p>
</dd>
</dl>
<p class="rubric">Examples</p>
<p>These are written in doctest format, and should illustrate how to
use the function.</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">a</span> <span class="o">=</span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span> <span class="p">[</span><span class="n">x</span> <span class="o">+</span> <span class="mi">3</span> <span class="k">for</span> <span class="n">x</span> <span class="ow">in</span> <span class="n">a</span><span class="p">]</span>
<span class="go">[4, 5, 6]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span> <span class="s2">&quot;a</span><span class="se">\n\n</span><span class="s2">b&quot;</span>
<span class="go">a</span>
<span class="go">b</span>
</pre></div>
</div>
</dd></dl>

</div>


          </div>
        </div>
          </div>
        </div>
      </div>
    </div>

    <div class="container container-navbar-bottom">
      <div class="spc-navbar">
        
      </div>
    </div>
    <div class="container">
    <div class="footer">
    <div class="row-fluid">
    <ul class="inline pull-left">
      <li>
        &copy; Copyright 2008-2019, The SciPy community.
      </li>
      <li>
      Last updated on Feb 20, 2020.
      </li>
      <li>
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.4.2.
      </li>
    </ul>
    </div>
    </div>
    </div>
  </body>
</html>